
\subsection{交流方式}

本项目主要使用 Issues / \href{https://jq.qq.com/?_wv=1027&k=5EfkM6K}{QQ} / \href{https://t.me/OIwiki}{Telegram} 进行交流沟通。

Telegram 群组链接为 \href{https://t.me/OIwiki}{@OIwiki} ， QQ 群号码为 \href{https://jq.qq.com/?_wv=1027&k=5EfkM6K}{\textbackslash{}texttt\{588793226\}}，欢迎加入。

\subsection{贡献方式}

\textbf{我们现在在使用 \href{https://github.com/24OI/OI-wiki/projects}{Projects}，这里详细列举了正在做的事情以及待做事项。}

\textbf{在开始编写一段内容之前，请查阅 \href{https://github.com/24OI/OI-wiki/issues}{Issues}，确认没有别人在做相同的工作之后，}

\textbf{开个 \href{https://github.com/24OI/OI-wiki/issues/new}{新 issue} 记录你要编写的内容。}

\subsubsection{我之前没怎么用过 GitHub}

参与 Wiki 的编写 \textbf{ 需要 } 一个 GitHub 账号， \textbf{ 不需要 } 高超的 GitHub 技巧。

举个栗子，假如我想要修改一个页面内容，应该怎么操作呢？

\begin{enumerate}
\item 在 OI Wiki 网站上找到对应页面。
\item 点击 正文右上方、目录左侧的 \textbf{“编辑此页”} edit 按钮。
\item （应该已经跳转到了 GitHub 上的对应页面吧？）这时候右上方还会有一个 \textbf{“编辑此页”} edit 的按钮，点击它就可以在线编辑了。
\item 写好了之后点下方的绿色按钮（Propose file change），可能会提示没有权限。不必担心！GitHub 会自动帮你 fork 一份项目的文件并创建 Pull Request。
\item 之后点上方的绿色按钮（Create pull request）后，再点一下出现的绿色按钮（Create pull request）。
\item 提交之后就可以等待他人合并或者指出还要修改的地方，当然你也可以给他人的 PR 提出修改意见，或者只是点赞 / 踩。如果有消息，会有邮件通知和 / 或网页上的提醒（取决于在你个人 Settings 中的设置）。
\end{enumerate}

（有木有很简单？）

如果还是不放心，可以参考\href{https://juejin.im/entry/56e638591ea49300550885cc}{这篇文章}。

\subsubsection{我之前用过 GitHub}

基本协作方式如下：

\begin{enumerate}
\item Fork 主仓库到自己的仓库中。
\item 当想要贡献某部分内容时，请务必仔细查看 \textbf{Issues}，以便确定是否有人已经开始了这项工作。当然，我们更希望你可以加入 QQ / Telegram 群组，方便交流。
\item 在决定将内容推送到本仓库时，\textbf{ 请你首先拉取本仓库代码进行合并，自行处理好冲突，同时确保在本地可以正常生成文档 }，然后再将分支 PR 到主仓库的 master 分支上。其中，PR 需要包含以下基本信息：
标题：本次 PR 的目的（做了什么工作，修复了什么问题）；
内容：如果必要的话，请给出对修复问题的叙述。
\end{enumerate}

\subsection{贡献文档要求}

当你打算贡献某部分的内容时，你应该尽量确保：

\begin{itemize}
\item 文档内容满足基本格式要求；
\item 文档的合理性；
\item 文档存储的格式。
\end{itemize}

\subsubsection{文档内容的基本格式}

在提交 PR 前，请先确保文档内容符合 \href{https://github.com/24OI/OI-wiki/wiki/\%E5%A6%82%E4%BD%95%E8%B4%A1%E7%8C%AE---How-to-contribute}{如何贡献 How to contribute} 中的格式要求。格式缺乏基本的规范性、严谨性可能会使你的贡献不能及时通过审核。

文档内容的基本格式主要是指 \href{https://github.com/ctf-wiki/ctf-wiki/wiki/\%E4%B8%AD%E6%96%87%E6%8E%92%E7%89%88%E6%8C%87%E5%8D%97}{中文排版指南} 与 \href{https://github.com/ctf-wiki/ctf-wiki/wiki/Mkdocs-\%E4%BD%BF%E7%94%A8%E8%AF%B4%E6%98%8E}{MkDocs 使用说明}。后者额外介绍了 mkdocs-material 主题的插件使用方式。

如果对 mkdocs-material （我们使用的这个主题）还有什么问题，还可以查阅 \href{https://cyent.github.io/markdown-with-mkdocs-material/}{cyent 的笔记}，他有介绍 markdown 传统语法和 mkdocs-material 支持的扩展语法。

\subsubsection{文档的合理性}

所谓合理性，指所编写的 \textbf{内容} 必须具有如下的特性：

\begin{itemize}
\item 由浅入深，内容的难度应该具有渐进性。
\item 逻辑性，对于每类内容的撰写应该尽量包含以下的内容：
\begin{itemize}
\item 原理，说明该内容对应的原理。
\item 例子，给出 1 \textasciitilde{} 2 个典型的例子。
\item 题目，在该标题下， \textbf{只需要给出题目名字、题目链接}。
\end{itemize}
\end{itemize}

\subsubsection{文档存储的格式}

对于每类要编写的内容，对应的文档应该存储在合适的目录下。

\begin{itemize}
\item images， 存储文档介绍时所使用的图片，位置为所添加的目录下（即格式为 \texttt{![](./images/xx.jpg)}）。
\item \textbf{文件名请务必都小写，以 \texttt{-} 分割， 如 \texttt{file-name}。}
\end{itemize}

\subsection{F.A.Q.}

\subsubsection{目录在哪}

目录在项目根目录下的 \href{https://github.com/24OI/OI-wiki/blob/master/mkdocs.yml#L17}{mkdocs.yml} 文件中。

\subsubsection{如何修改一个 topic 的内容}

在对应页面右上方有一个编辑按钮 edit，点击之后会跳转到 GitHub 上对应文件的位置。

或者也可以自行阅读目录 \href{https://github.com/24OI/OI-wiki/blob/master/mkdocs.yml#L17}{(mkdocs.yml)} 查找文件位置。

\subsubsection{如何添加一个 topic}

\begin{enumerate}
\item 可以开一个 Issue，注明希望能添加的内容。
\item 可以开一个 Pull Request，在目录 \href{https://github.com/24OI/OI-wiki/blob/master/mkdocs.yml#L17}{(mkdocs.yml)} 中加上新的 topic，并在 \href{https://github.com/24OI/OI-wiki/tree/master/docs}{docs} 文件夹下对应位置创建一个空的 \texttt{.md} 文件。
\end{enumerate}

\begin{NOTE}{}{}
写 .md 文件时，请勿在开头写上标题。

\end{NOTE}


\subsubsection{commit message 怎么写}

我们推荐使用 \href{https://github.com/commitizen/cz-cli}{commitizen/cz-cli} 来规范 commit message （并非强求）。

\subsubsection{我尝试访问 GitHub 的时候遇到了困难}

推荐在 hosts 文件中加入如下几行：（来源： \href{https://github.com/googlehosts/hosts/blob/master/hosts-files/hosts#L481-L485}{@GoogleHosts}）

\begin{minted}{text}
## GitHub Start
192.30.253.118  gist.github.com
192.30.253.112  github.com
192.30.253.112  www.github.com
## GitHub End
\end{minted}

可以在 \href{https://github.com/googlehosts/hosts}{@GoogleHosts 主页} 上了解到更多信息。

\subsubsection{我这里 pip 也太慢了}

可以选择更换国内源，参考：\href{https://blog.csdn.net/lambert310/article/details/52412059}{更改 pip 源至国内镜像 - L 瑜 - CSDN 博客}，或者：

\begin{minted}{bash}
pip install -U -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple/
\end{minted}

\subsubsection{我在客户端 clone 了这个项目，速度太慢}

如果有安装 \texttt{git bash}，可以加几个限制来减少下载量：

\begin{minted}{bash}
git clone https://github.com/24OI/OI-wiki.git --depth=1 -b master
\end{minted}

参考：\url{https://blog.csdn.net/FreeApe/article/details/46845555}

\subsubsection{我没装过 Python 3}

可以访问 \href{https://www.python.org/downloads/}{Python 官网} 了解更多信息。

\subsubsection{好像提示我 pip 版本过低}

进入 cmd / shell 之后，

\begin{minted}{bash}
python -m pip install --upgrade pip
\end{minted}

\subsubsection{我安装依赖失败了}

检查一下：网络？权限？查看错误信息？

\subsubsection{我已经 clone 下来了，为什么部署不了}

检查一下是否安装好了依赖？

\subsubsection{我 clone 了很久之前的 repo，怎么更新到新版本呢}

参考：\url{https://help.github.com/articles/syncing-a-fork/}。

\subsubsection{如果是装了之前的依赖怎么更新}

\begin{minted}{bash}
pip install -U -r requirements.txt
\end{minted}

\subsubsection{为什么我的 markdown 格式乱了}

可以查阅 \href{https://cyent.github.io/markdown-with-mkdocs-material/}{cyent 的笔记}，或者 \href{https://github.com/ctf-wiki/ctf-wiki/wiki/Mkdocs-\%E4%BD%BF%E7%94%A8%E8%AF%B4%E6%98%8E}{MkDocs 使用说明}。

我们目前在使用 \href{https://github.com/remarkjs/remark-lint}{remark-lint} 来自动化修正格式，可能还有一些 \href{https://github.com/24OI/OI-wiki/blob/master/.remarkrc}{配置} 不够好的地方，欢迎指出。

\paragraph{remark-lint 要求怎样的格式}

我们现在启用的配置文件在 \href{https://github.com/24OI/OI-wiki/blob/master/.remarkrc}{.remarkrc}，它可以自动给项目内文件统一风格。

在配置过程中我们也遇到了一些 remark-lint 不能很好处理的问题：

\begin{enumerate}
\item \texttt{\#\# 简介} 标题要空一格（英文半角空格），也不要写成 \texttt{\#\# 简介 \#\#}。
\item 列表
\begin{enumerate}
\item 列表前要有空行，新开一段。
\item \texttt{1. 例子} 点号后要有空格。
\end{enumerate}
\item 行间公式不能写在一行里，否则会被当做是行内公式
\item 伪代码请使用 \texttt{```text}
\end{enumerate}

\paragraph{GitHub 是不是不显示我的数学公式？}

是的，GitHub 的预览不显示数学公式。但是请放心，mkdocs 是支持数学公式的，可以正常使用，只要是 MathJax 支持的句式都可以使用。

\paragraph{我的数学公式怎么乱码了}

如果是行间公式（用的 \texttt{\$\$}），目前已知的问题是需要在 \texttt{\$\$} 两侧留有空行，且 \texttt{\$\$} 要 \textbf{单独} 放在一行里（且不要在前加空格）。格式如下：

\begin{minted}{text}
// 空行
$$
a_i
$$
// 空行
\end{minted}

\paragraph{我的公式为什么在目录里没有正常显示？好像双倍了？}

是的，这个是 python-markdown 的一个 bug，可能近期会修复。

如果现在想要避免目录中出现双倍公式，可以参考 \url{https://github.com/24OI/OI-wiki/blame/master/docs/string/sam.md#L82}

\begin{minted}{text}
### 结束位置 <script type="math/tex">endpos</script>
\end{minted}

在目录中会变成

\begin{minted}{text}
结束位置 endpos
\end{minted}

注：现在请尽量避免在目录中引入 MathJax 公式。

\subsubsection{如何给一个页面单独声明版权信息}

参考 \href{https://squidfunk.github.io/mkdocs-material/extensions/metadata/#usage}{Metadata} 的使用，在页面开头加一行即可。

比如：

\begin{minted}{text}
copyright: SATA
\end{minted}

注：默认的是 ‘CC BY-SA 4.0 和 SATA’。

\subsubsection{如何给一个页面关闭字数统计 （现已默认关闭）}

参考 \href{https://squidfunk.github.io/mkdocs-material/extensions/metadata/#usage}{Metadata} 的使用，在页面开头加一行即可。

比如：

\begin{minted}{text}
pagetime:
\end{minted}
